publish = false
```
-## Package metadata
+## Package Metadata
There are a number of optional metadata fields also accepted under the
`[package]` section:
# ...
# A short blurb about the package. This is not rendered in any format when
-# uploaded to crates.io (aka this is not markdown)
+# uploaded to crates.io (aka this is not markdown).
description = "..."
-# These URLs point to more information about the repository
+# These URLs point to more information about the repository.
documentation = "..."
homepage = "..."
repository = "..."
-# This points to a file in the repository (relative to this Cargo.toml). The
+# This points to a file in the repository (relative to this `Cargo.toml`). The
# contents of this file are stored and indexed in the registry.
readme = "..."
# This is a string description of the license for this package. Currently
# crates.io will validate the license provided against a whitelist of known
# license identifiers from http://spdx.org/licenses/. Multiple licenses can be
-# separated with a `/`
+# separated with a `/`.
license = "..."
# If a project is using a nonstandard license, then this key may be specified in
# lieu of the above key and must point to a file relative to this manifest
-# (similar to the readme key)
+# (similar to the readme key).
license-file = "..."
```
You can specify the source of a dependency in a few ways:
-* `git = "<git-url>"`: A git repository with a `Cargo.toml` inside it (not
- necessarily at the root). The `rev`, `tag`, and `branch` options are also
+* `git = "<git-url>"` refers to a git repository with a `Cargo.toml` inside it
+ (not necessarily at the root). The `rev`, `tag`, and `branch` options are also
recognized to use something other than the `master` branch.
-* `path = "<relative-path>"`: A path relative to the current `Cargo.toml`
- pointing to another directory with a `Cargo.toml` and an associated package.
-* If `path` and `git` are omitted, then a dependencies will come from crates.io
- and use the `version` key to indicate the version requirement.
+* `path = "<relative-path>"` refers to another directory with a `Cargo.toml`
+ inside it. The specified path should be relative to the current `Cargo.toml`.
+* If `path` and `git` are omitted, the dependency will come from crates.io, and
+ the `version` key will be used to indicate the version requirement.
Dependencies from crates.io can also use a shorthand where just the version
requirement is specified:
# The `[profile.*]` Sections
-Cargo supports custom configuration of how rustc is invoked through **profiles**
-at the top level. Any manifest may declare a profile, but only the **top level**
+Cargo supports custom configuration of how rustc is invoked through profiles at
+the top level. Any manifest may declare a profile, but only the top level
project’s profiles are actually read. All dependencies’ profiles will be
overridden. This is done so the top-level project has control over how its
dependencies are compiled.
along with the defaults for each profile.
```toml
-# The development profile, used for `cargo build`
+# The development profile, used for `cargo build`.
[profile.dev]
-opt-level = 0 # Controls the --opt-level the compiler builds with
-debug = true # Controls whether the compiler passes `-g`
-rpath = false # Controls whether the compiler passes `-C rpath`
-lto = false # Controls `-C lto` for binaries and staticlibs
-debug-assertions = true # Controls whether debug assertions are enabled
-codegen-units = 1 # Controls whether the compiler passes `-C codegen-units`
- # `codegen-units` is ignored when `lto = true`
-
-# The release profile, used for `cargo build --release`
+opt-level = 0 # controls the `--opt-level` the compiler builds with
+debug = true # controls whether the compiler passes `-g`
+rpath = false # controls whether the compiler passes `-C rpath`
+lto = false # controls `-C lto` for binaries and staticlibs
+debug-assertions = true # controls whether debug assertions are enabled
+codegen-units = 1 # controls whether the compiler passes `-C codegen-units`
+ # `codegen-units` is ignored when `lto = true`
+
+# The release profile, used for `cargo build --release`.
[profile.release]
opt-level = 3
debug = false
debug-assertions = false
codegen-units = 1
-# The testing profile, used for `cargo test`
+# The testing profile, used for `cargo test`.
[profile.test]
opt-level = 0
debug = true
debug-assertions = true
codegen-units = 1
-# The benchmarking profile, used for `cargo bench`
+# The benchmarking profile, used for `cargo bench`.
[profile.bench]
opt-level = 3
debug = false
debug-assertions = false
codegen-units = 1
-# The documentation profile, used for `cargo doc`
+# The documentation profile, used for `cargo doc`.
[profile.doc]
opt-level = 0
debug = true
# The `[features]` Section
-Cargo supports **features** to allow expression of:
+Cargo supports features to allow expression of:
-* Conditional compilation options (usable through `cfg` attributes);
-* Optional dependencies, which enhance a package, but are not required;
-* Clusters of optional dependencies, such as “postgres”, that would include the
+* conditional compilation options (usable through `cfg` attributes);
+* optional dependencies, which enhance a package, but are not required; and
+* clusters of optional dependencies, such as `postgres`, that would include the
`postgres` package, the `postgres-macros` package, and possibly other packages
- (such as development-time mocking libraries, debugging tools, etc.)
+ (such as development-time mocking libraries, debugging tools, etc.).
A feature of a package is either an optional dependency, or a set of other
features. The format for specifying features is:
name = "awesome"
[features]
-# The “default” set of optional packages. Most people will want to use these
+# The default set of optional packages. Most people will want to use these
# packages, but they are strictly optional. Note that `session` is not a package
# but rather another feature listed in this manifest.
default = ["jquery", "uglifier", "session"]
# like `#[cfg(feature = "go-faster")]`.
go-faster = []
-# The “secure-password” feature depends on the bcrypt package. This aliasing
+# The `secure-password` feature depends on the bcrypt package. This aliasing
# will allow people to talk about the feature in a higher-level way and allow
# this package to add more requirements to the feature in the future.
secure-password = ["bcrypt"]
session = ["cookie/session"]
[dependencies]
-# These packages are mandatory and form the core of this package’s distribution
+# These packages are mandatory and form the core of this package’s distribution.
cookie = "1.2.0"
oauth = "1.1.0"
route-recognizer = "=2.1.0"
# A list of all of the optional dependencies, some of which are included in the
-# above “features”. They can be opted into by apps.
+# above `features`. They can be opted into by apps.
jquery = { version = "1.0.2", optional = true }
uglifier = { version = "1.5.3", optional = true }
bcrypt = { version = "*", optional = true }
1. Feature names must not conflict with other package names in the manifest.
This is because they are opted into via `features = [...]`, which only has a
- single namespace
+ single namespace.
2. With the exception of the `default` feature, all features are opt-in. To opt
out of the default feature, use `default-features = false` and cherry-pick
individual features.
3. Feature groups are not allowed to cyclically depend on one another.
-4. Dev-dependencies cannot be optional
-5. Features groups can only reference optional dependencies
+4. Dev-dependencies cannot be optional.
+5. Features groups can only reference optional dependencies.
6. When a feature is selected, Cargo will call `rustc` with `--cfg
feature="${feature_name}"`. If a feature group is included, it and all of its
individual features will be included. This can be tested in code via
- `#[cfg(feature = "foo")]`
+ `#[cfg(feature = "foo")]`.
Note that it is explicitly allowed for features to not actually activate any
optional dependencies. This allows packages to internally enable/disable
features without requiring a new dependency.
-## Usage In End Products
+## Usage in End Products
One major use-case for this feature is specifying optional features in
end-products. For example, the Servo project may want to include optional
Default features could be excluded using `--no-default-features`.
-## Usage In Packages
+## Usage in Packages
-In most cases, the concept of “optional dependency” in a library is best
+In most cases, the concept of *optional dependency* in a library is best
expressed as a separate package that the top-level application depends on.
However, high-level packages, like Iron or Piston, may want the ability to
allows them to curate a number of mandatory dependencies into a single package
for easy installation.
-In some cases, packages may want to provide additional curation for **optional**
+In some cases, packages may want to provide additional curation for optional
dependencies:
-* Grouping a number of low-level optional dependencies together into a single
- high-level “feature”.
-* Specifying packages that are recommended (or suggested) to be included by
- users of the package.
-* Including a feature (like `secure-password` in the motivating example) that
+* grouping a number of low-level optional dependencies together into a single
+ high-level feature;
+* specifying packages that are recommended (or suggested) to be included by
+ users of the package; and
+* including a feature (like `secure-password` in the motivating example) that
will only work if an optional dependency is available, and would be difficult
- to implement as a separate package. For example, it may be overly difficult to
+ to implement as a separate package (for example, it may be overly difficult to
design an IO package to be completely decoupled from OpenSSL, with opt-in via
- the inclusion of a separate package.
+ the inclusion of a separate package).
In almost all cases, it is an antipattern to use these features outside of
high-level packages that are designed for curation. If a feature is optional, it
integration tests, and benchmarks respectively.
```notrust
-▾ src/ # directory containing source files
- lib.rs # the main entry point for libraries and packages
- main.rs # the main entry point for projects producing executables
- ▾ bin/ # (optional) directory containing additional executables
+▾ src/ # directory containing source files
+ lib.rs # the main entry point for libraries and packages
+ main.rs # the main entry point for projects producing executables
+ ▾ bin/ # (optional) directory containing additional executables
*.rs
-▾ examples/ # (optional) examples
+▾ examples/ # (optional) examples
*.rs
-▾ tests/ # (optional) integration tests
+▾ tests/ # (optional) integration tests
*.rs
-▾ benches/ # (optional) benchmarks
+▾ benches/ # (optional) benchmarks
*.rs
```
When you run `cargo test`, Cargo will:
-* Compile and run your library’s unit tests, which are in files reachable from
- `lib.rs`. Any sections marked with `#[cfg(test)]` will be included.
-* Compile and run your library’s documentation tests, which are embedded inside
- of documentation blocks.
-* Compile and run your library’s [integration tests](#integration-tests).
-* Compile your library’s examples.
+* compile and run your library’s unit tests, which are in the files reachable
+ from `lib.rs` (naturally, any sections marked with `#[cfg(test)]` will be
+ considered at this stage);
+* compile and run your library’s documentation tests, which are embedded inside
+ of documentation blocks;
+* compile and run your library’s [integration tests](#integration-tests); and
+* compile your library’s examples.
-## Integration tests
+## Integration Tests
Each file in `tests/*.rs` is an integration test. When you run `cargo test`,
Cargo will compile each of these files as a separate crate. The crate can link
the shared code in `tests/common/mod.rs` and then put `mod common;` in each of
the test files.
-# Configuring a target
+# Configuring a Target
All of the `[[bin]]`, `[lib]`, `[[bench]]`, `[[test]]`, and `[[example]]`
sections support similar configuration for specifying how a target should be
# is defaulted to the name of the package or project.
name = "foo"
-# This field points at where the crate is located, relative to the Cargo.toml.
+# This field points at where the crate is located, relative to the `Cargo.toml`.
path = "src/lib.rs"
# A flag for enabling unit tests for this target. This is used by `cargo test`.
# for Cargo to correctly compile it and make it available for all dependencies.
plugin = false
-# If set to false, `cargo test` will omit the --test flag to rustc, which stops
-# it from generating a test harness. This is useful when the binary being built
-# manages the test runner itself.
+# If set to false, `cargo test` will omit the `--test` flag to rustc, which
+# stops it from generating a test harness. This is useful when the binary being
+# built manages the test runner itself.
harness = true
```
[lib]
name = "..."
-# this could be “staticlib” as well
-crate-type = ["dylib"]
+crate-type = ["dylib"] # could be `staticlib` as well
```
The available options are `dylib`, `rlib`, and `staticlib`. You should only use
-this option in a project. Cargo will always compile **packages** (dependencies)
+this option in a project. Cargo will always compile packages (dependencies)
based on the requirements of the project that includes them.
projects / cargo.git / commitdiff